home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / filter < prev    next >
Text File  |  2001-04-06  |  3KB  |  61 lines
  1. SYNOPSIS
  2.         mixed * filter (mixed *arg, string fun, string|object ob
  3.                                               , mixed extra...)
  4.         mixed * filter (mixed *arg, closure cl, mixed extra...)
  5.         mixed * filter (mixed *arg, mapping map, mixed extra...)
  6.  
  7.         mapping filter (mapping arg, string func, string|object ob
  8.                                                 , mixed extra...)
  9.         mapping filter (mapping arg, closure cl, mixed extra...)
  10.  
  11. DESCRIPTION
  12.         Call the function <ob>-><func>() resp. the closure <cl> for
  13.         every element of the array or mapping <arg>, and return
  14.         a result made from those elements for which the function
  15.         call returns TRUE.
  16.  
  17.         If <ob> is omitted, or neither a string nor an object, it
  18.         defaults to this_object().
  19.  
  20.  
  21.         If <arg> is an array, the function will be called with
  22.         each of the mapping keys as first, and (if existing) the
  23.         associated values as second parameter, followed by the <extra>
  24.         arguments (these must not be protected references like &(i[0])). If
  25.         the result is true, the array element in question is included into the
  26.         result. Analog, if a mapping <map> is given instead of a function,
  27.         every array element which is key in <map> is included into the result.
  28.  
  29.  
  30.         If <arg> is a mapping, the function will be called with
  31.         each of the mapping keys as first, and (if existing) the
  32.         associated values as second parameter, followed by the <extra>
  33.         arguments. If the result is true, the mapping element in question
  34.         is included into the result.
  35.  
  36.         Depending on the width of the mapping <arg>, the function
  37.         call takes one of three forms:
  38.  
  39.             widthof(arg) == 0: ob->func(key, 0, extra...)
  40.                          == 1: ob->func(key, arg[key], extra...)
  41.                           > 1: ob->func( key
  42.                                        , ({ arg[key,0] ...arg[key,width-1] })
  43.                                        , extra...)
  44.  
  45.         The advantage of this approach is that the two types of
  46.         multi-dimensional mappings (mappings with multiple values
  47.         per key, and mappings of arrays) can be treated in the same way.
  48.  
  49.  
  50.         Note that filter() used with arrays behaves like filter_array(),
  51.         but used with mappings is a generalisation of filter_indices().
  52.  
  53.  
  54. HISTORY
  55.         Introduced in LDMud 3.2.6, obsoletes filter_array().
  56.  
  57. SEE ALSO
  58.         filter(E), filter_indices(E), map(E), walk_mapping(E), member(E),
  59.         m_contains(E)
  60.  
  61.